home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / mui / MCC_Mesa_dev.lha / developer / autodocs / MCC_Mesa.doc next >
Encoding:
Text File  |  1998-09-13  |  7.9 KB  |  272 lines
  1. TABLE OF CONTENTS
  2.  
  3. Mesa.mcc/Mesa.mcc
  4. Mesa.mcc/MUIA_Mesa_Base
  5. Mesa.mcc/MUIA_Mesa_Context
  6. Mesa.mcc/MUIA_Mesa_Display
  7. Mesa.mcc/MUIA_Mesa_DrawHook
  8. Mesa.mcc/MUIA_Mesa_DriverBase
  9. Mesa.mcc/MUIA_Mesa_Resized
  10. Mesa.mcc/MUIA_Mesa_ResizeHook
  11. Mesa.mcc/MUIA_Mesa_Tags
  12. Mesa.mcc/MUIA_Mesa_UseSubtask
  13. Mesa.mcc/MUIM_Mesa_Redraw
  14. Mesa.mcc/Mesa.mcc
  15.  
  16. This class allows you to use OpenGL graphics in MUI programs.
  17. Every Mesa object creates its own rendering context. You can use it and
  18. issue any GL commands, results will be visible after glFlush().
  19. Preferable way is to define a draw hook that will be called anytime mesa
  20. object needs to be refreshed.
  21.  
  22. Szymon Ulatowski, szulat@friko6.onet.pl
  23.  
  24.  Mesa MCC support site: 
  25. http://friko6.onet.pl/rz/szulat/mesamcc/
  26.  
  27.  AmigaMesaRTL:
  28. http://kcbbs.gen.nz/~jarno/
  29.  
  30. Mesa.mcc/MUIA_Mesa_Base
  31.  
  32.     NAME
  33.     MUIA_Mesa_Base -- [I.G], struct Library*
  34.  
  35.     FUNCTION
  36.    Gives you the "mesamain.library" base, being used by this object.  You
  37.    can also specify this tag at creation time to supply your own base (if
  38.    you want to share it across Mesa instances or open the library yourself).
  39.    Otherwise the object opens own library and you have to use this tag value
  40.    as the base for in Mesa function calls.
  41.  
  42.     NOTE
  43.    You may not share mesaBase when using subtask rendering in multiple
  44.    objects!
  45.  
  46.     SEE ALSO
  47.     MUIA_Mesa_DriverBase, MUIA_Mesa_Context, MUIA_Mesa_UseSubtask
  48.     
  49. Mesa.mcc/MUIA_Mesa_Context
  50.  
  51.     NAME
  52.     MUIA_Mesa_Context -- [..G], AmigaMesaRTLContext
  53.  
  54.     FUNCTION
  55.    This is Mesa rendering context used by the object.  You may need this value
  56.    for AmigaMesaRTL driver functions.
  57.  
  58.    In many common circumstances the object sets the context automaticaly.
  59.    You don't need to do call AmigaMesaRTLMakeCurrent() manually:
  60.     - after object creation
  61.     - in DrawHook
  62.     - in ResizeHook
  63.  
  64.     SEE ALSO
  65.     MUIA_Mesa_Base
  66.  
  67. Mesa.mcc/MUIA_Mesa_Display
  68.   
  69.     NAME
  70.     MUIA_Mesa_Mesa_Display -- [..G], int
  71.  
  72.     SPECIAL VALUES
  73.    MUIV_Mesa_Display_Hidden
  74.    MUIV_Mesa_Display_OK
  75.    MUIV_Mesa_Display_Unable
  76.    MUIV_Mesa_Display_Waiting
  77.  
  78.     FUNCTON
  79.    You can check here, what's the display status of your object.
  80.    Notification is also allowed.
  81.  
  82.    MUIV_Mesa_Display_Hidden:  object is not visible at the moment.  You can
  83.      use this to prevent from creating the graphics that nobody will see
  84.      (but it steals your cpu time)
  85.  
  86.    MUIV_Mesa_Display_OK:  quantizer was initialized properly and it claims
  87.      the picture is shown to the user
  88.  
  89.    MUIV_Mesa_Display_Unable: a quantizer can not be found or it can not
  90.      display in a given environment
  91.  
  92.    MUIV_Mesa_Display_Waiting: object is waiting for subtask to render
  93.      the graphics (only if MUIA_Mesa_UseSubtask is enabled)
  94.  
  95.  
  96.     EXAMPLE
  97.  
  98.    DoMethod(mesa_ob,MUIM_Notify,MUIA_Mesa_Display,MUIV_Mesa_Display_Unable,
  99.         mesa_ob,3,MUIM_Set,MUIA_ShortHelp,
  100.       "Alert! You have to select another quantizer module!");
  101.    DoMethod(mesa_ob,MUIM_Notify,MUIA_Mesa_Display,MUIV_Mesa_Display_OK,
  102.         mesa_ob,3,MUIM_Set,MUIA_ShortHelp,0);
  103.  
  104. Mesa.mcc/MUIA_Mesa_DrawHook
  105.  
  106.     NAME
  107.     MUIA_Mesa_DrawHook -- [IS.], struct Hook*
  108.  
  109.     FUNCTION
  110.    A given hook will be called every time mesa object needs to be
  111.    refreshed. You should put glFlush() at the end of your function if you
  112.    want to see something!
  113.    Before calling your hook the object's context is set as current, so you
  114.    don't have to call MakeCurrent().
  115.  
  116.     NOTES
  117.    When using subtask rendering, your hook function is executed by
  118.    a background task. You will receive SIGBREAKF_CTRL_D signal when
  119.    your mesa object wants to start a new rendering (eg. because 
  120.    the user changed some parameters and expects to see a new picture).
  121.     It's up to you what you do with this signal.
  122.    You can:
  123.     1.Abort the function and don't call glFlush()
  124.      - In that case Mesa will call it again from the begining
  125.         The user won't see the current drawing, but only the final
  126.       version.
  127.     2.Ignore the signal
  128.      - User will see your drawing and then mesa will start the next one
  129.       (so we delay that image)
  130.     3.Draw something quick
  131.      - You can draw a simplified version of the scene (or call glFlush
  132.       without drawing all objects)
  133.       It's the compromise: user will see some feedback immediately and
  134.       also the next image will not be delayed too much
  135.  
  136.    You should choose the action that is most proper for the application.
  137.    See the demo program for the complete example.
  138.    
  139.     EXAMPLE
  140.    Draw a wire sphere if the break signal is received or the solid
  141.    one under normal conditions.
  142.  
  143.     if (CheckSignal(SIGBREAKF_CTRL_D))
  144.          glutWireSphere(1.0, 20, 8);
  145.     else
  146.          glutSolidSphere(1.2, 20, 8); break;
  147.     glFlush();
  148.  
  149.  
  150.     SEE ALSO
  151.     MUIM_Mesa_Redraw, MUIA_Mesa_Base, MUIA_Mesa_Context, 
  152.    MUIA_Mesa_UseSubtask
  153.  
  154. Mesa.mcc/MUIA_Mesa_DriverBase
  155.  
  156.     NAME
  157.     MUIA_Mesa_DriverBase -- [..G], struct Library*
  158.  
  159.     FUNCTION
  160.    You can get the value of "mesadriverBase" here. If your object opens its own
  161.    library, you have to use this base in driver functions.
  162.    There is no need to use this tag in single-task or single-object
  163.    applications.
  164.  
  165.     SEE ALSO
  166.     MUIM_Mesa_Base
  167.  
  168. Mesa.mcc/MUIA_Mesa_Resized
  169.  
  170.     NAME
  171.     MUIA_Mesa_Resized -- [..G], BOOL
  172.  
  173.     FUNCTION
  174.    TRUE means the object was resized recently and needs a glViewport()
  175.    call. You can set up a notification on this tag or use it normal way
  176.    (eg. in your redraw funtion)
  177.  
  178.     SEE ALSO
  179.     MUIA_Mesa_ResizeHook
  180.  
  181. Mesa.mcc/MUIA_Mesa_ResizeHook
  182.  
  183.     NAME
  184.     MUIA_Mesa_ResizeHook -- [IS.], struct Hook*
  185.  
  186.     SPECIAL INPUT
  187.    MUIV_Mesa_ResizeHook_DefaultViewport
  188.  
  189.     FUNCTION
  190.    Your hook will be called each time the object is resized and you should
  191.    use glViewport() to set display rectangle for Mesa.
  192.    Before calling your hook the proper context is set as current, so you
  193.    don't have to call MakeCurrent().
  194.    Your hook function will receive a pointer to MCCMesaResizeData in A1:
  195.  
  196.    struct MCCMesaResizeData {long Width,Height;};
  197.  
  198.    'Width' and 'Height' are of course the new display size for your object.
  199.  
  200.    MUIV_Mesa_ResizeHook_DefaultViewport will automatically call
  201.    glViewport(0,0,Width,Height), this may be sufficient in many simple
  202.    cases.
  203.  
  204.  
  205.     SEE ALSO
  206.     MUIA_Mesa_Resized, MUIA_Mesa_Base, MUIA_Mesa_Context
  207.  
  208. Mesa.mcc/MUIA_Mesa_Tags
  209.  
  210.     NAME
  211.     MUIA_Mesa_Tags -- [I..]
  212.  
  213.     FUNCTION
  214.    Here you can specify initial Mesa tags.  You give a pointer to the tag
  215.    array that will be passed to AmigaMesaRTLCreateContext. Probably you
  216.    need to put here {AMRTL_RGBMode,TRUE,TAG_END} or
  217.    {AMRTL_IndexMode,TRUE,TAG_END}
  218.  
  219. Mesa.mcc/MUIA_Mesa_UseSubtask
  220.  
  221.     NAME
  222.    MUIA_Mesa_UseSubtask -- [I..], BOOL
  223.  
  224.     FUNCTION
  225.    If TRUE, mesa will spawn a new background task for your DrawHook
  226.    and window refresh will not be blocked by mesa objects refreshing.
  227.    3D rendering can be very time consuming so you should always
  228.    use this tag if you can make your application work safe in
  229.    multitasking. 
  230.    
  231.    Default is FALSE.
  232.  
  233.     NOTES
  234.  
  235.    1. When using this feature, every object has to use different
  236.    mesamainBase (and also glut.library if you use it). This means
  237.    you have to get MUIA_Mesa_Base from the newly created object
  238.    and call the GL functions relative to this base. The only exception
  239.    is if you have only one mesa object, you can use global mesa
  240.    base in that case.
  241.  
  242.    2. Mesa drawing functions use lot of stack space. If you don't use
  243.    subtask rendering, your main task should have stack bigger than
  244.     70000. Object creation will fail otherwise.
  245.    With 'UseSubtask' enabled, the new process will automaticaly get
  246.    a big stack.
  247.  
  248.    3.  You should check if your application supports multitasking.  Is it
  249.    designed to let many tasks access the data used by your drawing routine?
  250.  
  251.  
  252.     SEE ALSO
  253.    MUIA_Mesa_Base, MUIA_Mesa_DrawHook
  254.  
  255.  
  256. Mesa.mcc/MUIM_Mesa_Redraw
  257.  
  258.     NAME
  259.     MUIM_Mesa_Redraw
  260.  
  261.     FUNCTON
  262.    Ask the object to redraw itself (DrawHook will be called).
  263.    
  264.     EXAMPLE
  265.    A button starts image rendering:
  266.  
  267.    DoMethod(button,MUIM_Notify,MUIA_Selected,0,
  268.         mesa_ob,1,MUIM_Mesa_Redraw);
  269.  
  270.     SEE ALSO
  271.     MUIA_Mesa_DrawHook
  272.